Documentation on uvgen

Task: uvgen
Purpose: Compute visibilities for a model source.
Categories: uv analysis, map making

        UVGEN is a MIRIAD task which computes visibility data for a model
        source distribution at u-v data points specified by a set of
        antenna positions, hour angle range and sample interval. The model
        is specified by a set of Gaussian sources with given positions and
        flux densities. Analytic expressions are used to calculate the
        value of the visibilities. The calculation includes the response to
        polarized sources with linear and circularly polarized feeds. U-V
        trajectories for all pairs of antennas are computed.

Key: source
        The name of a text file containing the source components. The
        default is "uvgen.source". If the specified model components file
        does not exist, UVGEN interactively prompts the user for information,
        and then generates the file. The source components are elliptical
        Gaussian components described by the total flux (Jy) and
        position offsets (arcsecs) from the phase center in the directions
        of ra and dec. The sources are specified by the full width to half
        maximum of the major and minor axes; the position angle of the
        major axis measured from north to the east. The default half width
        for a "point" source is 0."0001. The sources can be partially linearly
        polarized. This information is given as a percentage polarization and
        a position angle. A value of 0 for the percentage polarization forms
        an unpolarized source.

Key: ant
        The name of a text file containing the position of the antennae.
        The default is "uvgen.ant". If the specified antenna file does
        not exist, UVGEN interactively prompts the user for the coordinates
        of the antennas, and then generates the antenna file.
        The antenna positions can be given in either a right handed
        equatorial system or as a local ground based coordinates measured to the
        north, east and in elevation. See the "baseunit" parameter to
        specify the coordinate system. Some standard antenna configurations
        can be found in $MIRCAT/*.ant for ATCA, BIMA and VLA telescopes.
        The BIMA antpos files can also be used with baseunit=1.

Key: baseunit
        This specifies the coordinate system used in the antenna file.
        A positive value for "baseunit" indicates an equatorial system,
        whereas a negative value indicates a local system. The magnitude of
        "baseunit" gives the conversion factor between the baseline units
        used in the antenna file, and nanoseconds. The default value is +1,
        which means that the antenna file gives the antenna position in an
        equatorial system measured in nanoseconds.
        E.g. 	baseunit=-1 for topocentric coordinates in nanosecs, 
        	baseunit=3.33564 for geocentric coordinates in meters.

Key: telescop
        This can take on the value of "hatcreek", "atca" or "other".
        This determines miscellaneous parameters. In particular, this
        determines the interpretation of the correlator setup file
        (see below), the "evector" variable and the telescope name.
        The default is "hatcreek".

Key: corr
        This gives the name of a text file specifying the correlator
        setup, and a spectral line model. The default name is "uvgen.corr".
        If it does not exist, UVGEN prompts interactively, and then creates
        the file.
        The values are:
          Number of channels in each spectral window. 0=wideband only.
          Number of spectra: up to 4 spectral windows can be specified.
          Four starting frequencies and bandwidths for each spectral window. 
           These are specified in MHz. For other than Hat Creek, only
           the first correlator bandwidth is used.
           No checking is made for valid combinations.
          Three parameters, famp, fcen and fwid, giving line to continuum
           ratio, freq and width (GHz). This gives a simple spectral line.
           In particular, the visibility value for a channel is scaled by
           a factor:
            1 + famp*( 1-min(1,|(f-fcen)/fwid|) )

Key: time
        The time of the observation (this corresponds to ha=0). This is in
        the form
          yymmmdd.ddd
        or
          yymmmdd:hh:mm:ss.s
        The default is 80JAN01.0. A function of this is also used
        as a seed for the random number generator.

Key: freq
        Frequency and 2nd IF frequency for the model in GHz.
        Defaults are 100,0.250 GHz. 
        The IF parameter is currently ignored if the telescope is not 
        hatcreek.

Key: radec
        Source right ascension and declination. These can be given in
        hh:mm:ss,dd:mm:ss format, or as decimal hours and decimal
        degrees. The default is 0,30.

Key: harange
        Hour Angle range (start,stop,step) in hours. Default is
        -6 hrs to + 6 hrs, with a sample interval=0.1 (6 minute)

Key: elev
        Elevation limit in degrees. Default=15 degrees. Both harange
        and elev are used to limit the extent of the u-v track.

Key: stokes
        This selects the polarization parameters formed. Up to 4
        polarizations can be formed in one run . They can be 'i' (default),
        'xx', 'yy', 'xy', 'yx, 'lr', 'rl', 'rr' or 'll'. For example:
          stokes=xx,yy,xy,yx
        will form a file with the 4 polarisations corresponding to an array
        with linear feeds.
        For linear feeds the convention is that the X feed has a position
        angle of 0, and the Y feed is 90 (measured north towards east).

Key: polar
        Polarization patterns for generating time shared polarization data. 
        Up to MAXPOLAR=20 strings of the characters R and L, or X and Y, 
        to represent the polarization of each antenna
        R(right circular polarization), L(left circular polarization)
        X(linear polarization PA=0), Y(linear polarization PA=90).
        E.g. for 3 antennas, the polar=LLL,LRR,RRL,RLR cycles
        through all combinations of LCP and RCP for each baseline every
        4 integrations. The default is to use the stokes keyword.

Key: leakage
        Polarization leakage errors, given as a percent. This gives the
        rms value of leakages of one polarisation feed into another.
        Polarization leakage errors are constant over the observation.
        To use this, you must set
          stokes=xx,yy,xy,yx
        or
          stokes=rr,ll,rl,lr
        The default is 0 (i.e. no polarization leakage).

Key: lat
        Latitude of observatory, in degrees. Default is 40 degrees.

Key: cycle
        This gives two values, being the time on-source, and the time
        off-source cycle times, both in hours. This allows simulation of
        time segments lost while observing calibrators, etc. For example,
        if simulating an observation which observes the source for 24 minutes
        and then is off-source (observing a calibrator) for 6 minutes, use:
          cycle=0.4,0.1
        Similarly, if simulating this calibrator, use:
          cycle=0.1,0.4
        The default is harange(3),0 (i.e. do not interrupt the observations).

Key: pbfwhm
        The primary beam fwhm, in arcseconds. The value of this will be
        approximately 66000/(diam*freq), where "diam" is the antenna
        diameter in meters, and "freq" is the observing frequency. The
        default is an infinite primary beam (i.e. no primary beam effects).

Key: center
        Offset observing centers for a mosaiced observation, in arcseconds.
        Two values (x and y offset) are required per pointing. Several
        values can be given. Default is 0,0 (i.e. a plain, single pointing
        observation). The time spent on each pointing is given by the value of
        ``cycle(1)''. Note that the default value of cycle(1) means that the
        observing center changes every integration.

Key: gnoise
        Antenna based gain noise, given as a percentage. This gives the
        multiplicative gain variations, specified by the rms amplitude to be
        added to the gain of each antenna at each sample interval. The
        gain error stays constant over the period given by the ``cycle(1)''
        parameter (see above). Thus ``cycle(1)'' can be varied to give
        different atmosphere/instrument stabilities. Note that the default
        of the ``cycle'' parameter means that the gain changes every
        integration. 

        A gain error can also be used to mimic random pointing errors
        provided the source is a point source.
        The default is 0 (i.e. no gain error).

Key: pnoise
        Antenna based phase noise, in degrees. This gives the phase
        noise, specified by the rms phase noise to be added to each
        antenna. Up to 4 values can be given to compute the phase noise
          pnoise(1) + pnoise(2)*(baseline)**pnoise(3)*sinel**pnoise(4)
        where ``baseline'' is the baseline length in km. Typical values
        for pnoise(2) are 1mm rms pathlength (e.g. 2 radians at 100 GHz),
        For Kolmogorov turbulence pnoise(3)=5/6 for baseline   100m
        and 0.33 for baseline   100m (outer scale of turbulence).
        pnoise(4)=-0.5 for a thick turbulent screen, and -1 for a thin layer.
        See also the ``gnoise'' parameter. Default is 0,0,0,0 (i.e.
        no phase error).

Key: systemp
        System temperature used to compute additive random noise and
        total power. One or 3 values can be given; either the average
        single sideband systemp including the atmosphere (TELEPAR gives
        typical values), or the double sideband receiver temperature, 
        sky temperature, and zenith opacity, when systemp is computed as:
         systemp = 2.*(Trx + Tsky*(1-exp(-tau/sinel)))*exp(tau/sinel)
        where systemp, Trx and Tsky are in Kelvin. Typical values for Hat Ck
        Trx, Tsky, and tau are 75,290,0.15. (OBSTAU gives values for tau).
        systemp is used	to generate random Gaussian noise to add to each 
        data point. Default is 0,0,0 (i.e. no additive noise).

Key: tpower
        Two values can be given to represent the total power variations
        due to receiver instability (Trms), and atmospheric noise (Tatm). 
                 tpower = Trms * systemp +  Tatm * pnoise
        The receiver instablity is modeled as multiplicative Gaussian noise.
        The atmospheric noise is modeled to be correlated with the antenna
        phase noise. Typical values at 3 millimeter wavelength
        are Trms=10-3 and Tatm=0.2 K/radian (280 degrees/K).
        Default is tpower=0,0

Key: jyperk
        The system sensitivity, in Jy/K. Its value is given by 2*k/(eta * A)
        where k is Boltzmans constant (1.38e3 Jy m**2 / K), A is the physical
        area of each antenna (pi/4 * D**2), and eta is an efficiency.
        For the ATCA, D is 22 meters, and eta is composed of a correlator
        efficiency (0.88) and an antenna efficiency (0.65 at 6 cm). The
        overall result is jyperk=12.7. The default jyperk=150, a typical
        value for the Hat Creek 6.1 m antennas.

Key: out
        This gives the name of the output Miriad data file. The default
        it "uvgen". If the dataset exists, visibilities are appended to
        the dataset, with an appropriate informational message.